<html id="text-tutorial" xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Introduction to Text and Fonts</title>
</head>

<body>
<h1>Introduction to Text and Fonts</h1>
<h2>Introduction</h2>

<p>This tutorial shows how to work with text and fonts in OpenLaszlo applications. Later chapters on 
<xref linkend="text">Text Views</xref> and <xref linkend="fonts">fonts</xref>
explain more advanced topics.</p>


<h2>Working with text</h2>

<h2><a name="basics"/>The &lt;text&gt; tag</h2>

<p>Entering text is easy with the <tagname>text</tagname> tag:</p>

<example class="code" title="The simple &lt;text&gt; tag">
&lt;canvas height="100" width="500" &gt;
  &lt;text&gt;
    Hello, World!
  &lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>Text that is beween the <tagname>text</tagname> tags is normalized, meaning that preceding and trailing whitespace is ignored, as are multiple whitespace elements between words. i.e. if you put several spaces between words, it the output will still be a single space. If you put a line break in the text, it will be rendered as a single whitespace element (i.e. a space), and text fields will stretch to fit their contents.</p>

<p>The default OpenLaszlo font is used (LzTahoe), at its default size (10px).</p>

<p>The <tagname>text</tagname> tag is a view, so it can be treated as one. It can be given all the default view attributes, such as width, x, y and so forth.</p>


<example class="code" title="&lt;text&gt; is a &lt;view&gt;">
&lt;canvas height="100" width="500"&gt;
  &lt;text <em>x="15" y="20" width="150"</em>&gt;
    Hello, World!
    We would like to welcome you to the launch of the Laszlo Presentation
    Server.
  &lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>Notice how the text gets cut off because we set the width attribute? </p>


<h2><a name="multiline"></a>Multiline text</h2>

<p>Having multiline areas of text is just as easy. All we do is set the <attribute>multiline</attribute> attribute to <code>true</code>:</p>

<example class="code" title="Multiline text">
&lt;canvas height="100" width="500"&gt;
  &lt;text x="15" y="20" width="150" <em>multiline="true"</em>&gt;
    Hello, World!
    We would like to welcome you to the launch of the Laszlo Presentation
    Server.
  &lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>The text stills follow the same normalization rules, so in this case the text wraps at 150px (because we explicitly set the width of the <tagname>text</tagname> tag to that), and stretches vertically as far as it needs to go.</p>

<p>The line breaks are still being ignored, but we can fix that by entering them manually:</p>

<example class="code" title="Inserting line breaks">
&lt;canvas height="100" width="500"&gt;
   &lt;text x="15" y="20" width="150" multiline="true"&gt;
      Hello, World!<em>&lt;br /&gt;&lt;br /&gt;</em>
      We would like to welcome you to the launch of the Laszlo Presentation
      Server.
   &lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>The <tagname>br</tagname> tag is used to denote a single line break. This may be familiar to you from HTML. Just be careful to note that since we are working in XML, empty elements have to be closed with a forward slash: <code>&lt;br/&gt;</code>. (This is the same as in XHTML.)</p>

<p>If you've had any experience with HTML in the past, you are no doubt wondering if you can use other HTML tags. The answer is yes. Below is a list of tags that are supported:</p>

<todo>Find out if P tag has been made obsolete.</todo>

<table>
<tr>
  <th>Tag</th>
  <th>Meaning</th>
</tr>
<tr>
  <td>
    <tagname>a</tagname>
  </td>
  <td>
    <p>Hypertext Link</p>
  </td>
</tr>
<tr>
  <td>
    <tagname>b</tagname>
  </td>
  <td>
    <p>Bold Text</p>
  </td>
</tr>
<tr>
  <td>
    <tagname>font</tagname>
  </td>
  <td>
    <p>Defines and implements fonts</p>
  </td>
</tr>
<tr>
  <td>
    <tagname>i</tagname>
  </td>
  <td>
    <p>Italic text</p>
  </td>
</tr>
<tr>
  <td>
    <tagname>p</tagname>
  </td>
  <td>
    <p>Paragraph</p>
  </td>
</tr>
<tr>
  <td>
    <tagname>u</tagname>
  </td>
  <td>
    <p>Underline</p>
  </td>
</tr>
</table>

<example class="code" title="specifying a font">
&lt;canvas height="150" width="500"&gt;
  &lt;font name="default" style="bold" src="lztahoe8b.ttf"/&gt;
  &lt;text x="15" y="20" width="150" multiline="true"&gt;
    &lt;b&gt;Hello, <em>&lt;font color="#ff0000"&gt;</em>World!<em>&lt;/font&gt;</em>&lt;/b&gt;&lt;br /&gt;&lt;br /&gt;
<em>&lt;font size="16"&gt;</em>We<em>&lt;/font&gt;</em> would like to welcome <em>&lt;u&gt;</em>you<em>&lt;/u&gt;</em> to the 
      launch of the <em>&lt;a href="http://www.laszlosystems.com/"&gt;</em>Laszlo<em>&lt;/a&gt; </em>
      Presentation Server.
  &lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>The word "Laszlo" becomes a hyperlink because of the <tagname>a</tagname> tag. It does not get underlined as it might in a browser. We can do that ourselves by nesting a <tagname>u</tagname> tag inside it. However, it is important to note that tags must be nested correctly:</p>

<pre>&lt;a href="..."&gt;<em>&lt;u&gt;</em>Link<em>&lt;/u&gt;</em>&lt;/a&gt;</pre>

<p>is correct, but</p>

<pre>&lt;a href="..."&gt;<em>&lt;u&gt;</em>Link&lt;/a&gt;<em>&lt;/u&gt;</em></pre>

<p>is wrong because the <tagname>a</tagname> tag was closed before the <tagname>u</tagname> tag.</p>



<h2><a name="fonts"></a>Fonts</h2>

<p>Laszlo supports TrueType fonts, and the simplest way to use one is as follows:</p>

<example class="code" title="Naming a font family">
&lt;canvas height="100" width="500"&gt;
   &lt;font name="serifFont" src="timmonsr.ttf"/&gt;
   &lt;text width="150" height="20"&gt;
      &lt;font face="serifFont" size="14"&gt;Hello, World!&lt;/font&gt;
   &lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>We called this font <i>serifFont</i>, but we could call it whatever we wanted, and that is what will be used to declare its use elsewhere in the application.</p>

<p>The font TTF files can be located in the current directory or another one and referenced relatively (<code>src="../fonts/..."</code>). Otherwise they are included in the LPS webapp directory of the installation under WEB-INF/lps/fonts. timonnsr is a font that comes packaged with the LPS in this location.</p>

<p>A truetype file is required for each style of font (e.g. italic, bold, regular), which is how fonts are actually packaged. So the following code will <b>not</b> work:</p>


<example class="code" extract="false">
&lt;canvas&gt;
   &lt;!-- WARNING: Bad example! --&gt;
   &lt;font name="serifFont" src="timmonsr.ttf"/&gt;
   &lt;text width="150" height="20"&gt;
      &lt;font face="serifFont" size="14"&gt;Hello, <em>&lt;b&gt;</em>World!<em>&lt;/b&gt;</em>&lt;/font&gt;
   &lt;/text&gt;
&lt;/canvas&gt;
</example>


<p>To correct this, we need to add one line of code to include the bold font:</p>


<example class="code" title="including bold font">
&lt;canvas height="100" width="500"&gt;
   <em>&lt;font name="serifFont"&gt;
      &lt;face src="timmonsr.ttf"/&gt;
      &lt;face src="timmonsb.ttf" style="bold"/&gt;
   &lt;/font&gt;</em>
   &lt;text width="150" height="20"&gt;
      &lt;font face="serifFont" size="14"&gt;Hello, &lt;b&gt;World!&lt;/b&gt;&lt;/font&gt;
   &lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>The plain font style does not need to be explicitly set; <code>style="plain"</code> is implied. This method of markup is not always the best solution, because it depends on writing cumbersome <tagname>font</tagname> tags. </p>
<p>Instead we can tell the <tagname>text</tagname> tag what fonts and sizes to use:</p>

<example class="code" title="assigning fonts to &lt;text&gt; tag">
&lt;canvas height="100" width="500"&gt;
   &lt;font name="serifFont"&gt;
      &lt;face src="timmonsr.ttf"/&gt;
      &lt;face src="timmonsb.ttf" style="bold"/&gt;
   &lt;/font&gt;

   &lt;text width="150" height="150"
   <em>font="serifFont" fontsize="15"</em> multiline="true"&gt;
      Hello, &lt;b&gt;World!&lt;/b&gt;&lt;br /&gt;
         Sometimes it is easier to avoid writing extra &lt;u&gt;font&lt;/u&gt; tags.
   &lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>In fact, we can do this with any view (including <tagname>window</tagname> tags, and so forth) tag, and its children will inherit the fonts that were set:</p>

<example class="code" title="Views inherit font properties">
&lt;canvas height="100" width="500"&gt;
   &lt;font name="serifFont"&gt;
      &lt;face src="timmonsr.ttf"/&gt;
      &lt;face src="timmonsb.ttf" style="bold"/&gt;
   &lt;/font&gt;

   &lt;view name="grandParent" <em>font="serifFont" fontsize="15"</em>&gt;
      &lt;view name="firstView" bgcolor="#FFCCCC" height="20"&gt;
         &lt;text&gt;Hello&lt;/text&gt;
      &lt;/view&gt;
      &lt;view x="80" name="secondView" bgcolor="#CCCCFF" height="20"&gt;
         &lt;text&gt;World&lt;/text&gt;
      &lt;/view&gt;
   &lt;/view&gt;
&lt;/canvas&gt;
</example>

<p>The font here is specified in the <i>grandParent</i> view, and it is inherited by both text fields.</p>

<p>Of course font specifications can be overridden further down the hierarchy, both through the use of <tagname>font</tagname> tags, and by defining fonts specifications of child views:</p>

<example class="code" title="Overwriting font specifications">
&lt;canvas height="100" width="500"&gt;
  &lt;font name="serifFont"&gt;
    &lt;face src="timmonsr.ttf"/&gt;
    &lt;face src="timmonsb.ttf" style="bold"/&gt;
  &lt;/font&gt;
  
  <em>&lt;font name="sansSerifFont" src="helmetr.ttf" /&gt;</em>
  
  &lt;view name="grandParent" font="serifFont" fontsize="15"&gt;
    &lt;view name="firstView" bgcolor="#FFCCCC" height="20"&gt;
      &lt;text&gt;
        <em>&lt;font color="#CC6600" size="12"&gt;</em>Hello<em>&lt;/font&gt;</em>
      &lt;/text&gt;
    &lt;/view&gt;
    &lt;view x="80" name="secondView" bgcolor="#CCCCFF" height="20"&gt;
      &lt;text <em>font="sansSerifFont"</em>&gt;World&lt;/text&gt;
    &lt;/view&gt;
  &lt;/view&gt;
&lt;/canvas&gt;
</example>

<p>Both the text fields here have overridden some of the font specs. The ones that aren't overridden (such as the face in the left example and the size in the right example) are inherited.</p>


<h2><a name="changing"></a>Changing Text</h2>

<p>The <tagname>text</tagname> element has two methods for reading and writing contents:</p>
<ul>
  <li><method>getText</method></li>
  <li><method>setText</method></li>
</ul>

<p>The <method>getText</method> method returns the contents of the text box, and the <method>setText</method> method takes an argument of the string to put in the text field:</p>

<example class="code" title="Getting and setting text">
&lt;canvas height="135" width="700" debug="true"&gt;
   &lt;debug x="200"/&gt;
   &lt;button x="15" y="15"
      onclick="Debug.write(canvas.theField.getText());"&gt;
      Get Text 
   &lt;/button&gt;

   &lt;button x="100" y="15"
      onclick="canvas.theField.setText('Hello, Laszlo!');"&gt;
         Set Text
   &lt;/button&gt;

   &lt;button x="180" y="115"
      onclick="addText();"&gt;
         Add Text
   &lt;/button&gt;

   &lt;script&gt;
      function addText() {
      var origText = canvas.theField.getText();
      var newText = origText + " And on.";
           canvas.theField.setText(newText);
      }
   &lt;/script&gt;

   &lt;text x="45" y="60" width="150" height="75" multiline="true"
      name="theField"&gt;Some sample text.&lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>Using these two methods, it is possible to concatanate text, and work with it as a string.</p>

<p>An important thing to remember when working with text is that everything between the <tagname>text</tagname> tags is returned by <method>getText</method>.</p>


<example class="code" title="text returned">
&lt;canvas height="135" width="700" debug="true"&gt;
    &lt;debug x="200"/&gt;
   &lt;font name="sansSerifFont" src="helmetr.ttf" /&gt;

   &lt;script&gt;
      function writeOutBit() {
      var myText = canvas.theField.getText();
      <em>Debug.write(myText);</em>
   }
   &lt;/script&gt;

   &lt;button x="15" y="15"
      onclick="writeOutBit();"&gt;
         Write part of line
   &lt;/button&gt;
  
   &lt;text x="45" y="60" width="150" height="75" multiline="true"
      name="theField"&gt;
      &lt;font face="sansSerifFont" size="12"&gt;Some lovely sample 
      text.
      &lt;/font&gt;
   &lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>This can be both useful and a nuisance. If we were to start parsing the string that is returned by the <method>getText</method> method, then we would have to compensate for the markup tags. To avoid it, set the font in the <tagname>text</tagname> tag.</p>


<h2><a name="input"></a>Input Text</h2>

<p>The simplest way to provide users with a text field is with the <tagname>inputtext</tagname> tag:</p>

<example class="code" title="Using &lt;inputtext&gt;">
&lt;canvas height="135" width="700" debug="true"&gt;
    &lt;debug x="200"/&gt;
   &lt;inputtext name="myText" x="10" y="15"&gt;Enter text here&lt;/inputtext&gt;
   &lt;button x="45" y="45"
      onclick="Debug.write(canvas.myText.getText());"&gt;
         Write out text 
   &lt;/button&gt;
&lt;/canvas&gt;
</example>

<p>The <tagname>inputtext</tagname> field gives no indication that the text can be selected and edited, other than an insert cursor when the user rolls over it. The <tagname>inputtext</tagname> element can accept all the <tagname>text</tagname> attributes, as well as fonts:</p>

<example class="code" title="&lt;inputtext&gt; accepts &lt;text&gt; attributes">
&lt;canvas height="100" width="500"&gt;
  &lt;font name="Helmet" src="helmetr.ttf" /&gt;
  &lt;inputtext name="myText" x="10" y="15"
      font="Helmet" fontsize="12"
      width="200" height="50" multiline="true"&gt;
         Enter very large quantities of text here.
  &lt;/inputtext&gt;
&lt;/canvas&gt;
</example>

<p><code>getText</code> and <code>setText</code> methods will work on <tagname>inputtext</tagname> fields as well.</p>

<p>To overcome the problem of the text field not being recognizeable, Laszlo provides the <tagname>edittext</tagname> tag:</p>

<example class="code" title="Using &lt;edittext&gt;">
&lt;canvas height="160" width="500"&gt;
   &lt;edittext name="myText" x="10" y="15"&gt;Enter text here&lt;/edittext&gt;

   &lt;edittext name="myBigText" x="10" y="45"
      width="250" height="100" multiline="true"&gt;
         Enter a lot more text here
   &lt;/edittext&gt;
&lt;/canvas&gt;
</example>

<p>The <tagname>edittext</tagname> tag can be multiline, and can be adjusted in size.</p>

</body>
</html>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2001-2004 Laszlo Systems, Inc.  All Rights Reserved.              *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->
